home *** CD-ROM | disk | FTP | other *** search
/ Aminet 15 / Aminet 15 - Nov 1996.iso / Aminet / dev / gcc / ixemsdk.lha / man / cat3 / recno.0 < prev    next >
Text File  |  1996-09-02  |  6KB  |  199 lines
  1.  
  2.  
  3.  
  4. RECNO(3)                                                 RECNO(3)
  5.  
  6.  
  7. NNAAMMEE
  8.        recno - record number database access method
  9.  
  10. SSYYNNOOPPSSIISS
  11.        ##iinncclluuddee <<ssyyss//ttyyppeess..hh>>
  12.        ##iinncclluuddee <<ddbb..hh>>
  13.  
  14. DDEESSCCRRIIPPTTIIOONN
  15.        The  routine  _d_b_o_p_e_n  is the library interface to database
  16.        files.  One of the supported file formats is record number
  17.        files.   The  general  description  of the database access
  18.        methods is in _d_b_o_p_e_n(3), this manual page  describes  only
  19.        the recno specific information.
  20.  
  21.        The  record  number  data  structure is either variable or
  22.        fixed-length  records  stored  in  a   flat-file   format,
  23.        accessed  by  the logical record number.  The existence of
  24.        record number five implies the existence  of  records  one
  25.        through four, and the deletion of record number one causes
  26.        record number five to be renumbered to record number four,
  27.        as  well  as the cursor, if positioned after record number
  28.        one, to shift down one record.
  29.  
  30.        The recno access method specific data  structure  provided
  31.        to  _d_b_o_p_e_n  is  defined in the <db.h> include file as fol-
  32.        lows:
  33.  
  34.        typedef struct {
  35.               u_long flags;
  36.               u_int cachesize;
  37.               u_int psize;
  38.               int lorder;
  39.               size_t reclen;
  40.               u_char bval;
  41.               char *bfname;
  42.        } RECNOINFO;
  43.  
  44.        The elements of this structure are defined as follows:
  45.  
  46.        flags  The flag value is specified by _o_r'ing  any  of  the
  47.               following values:
  48.  
  49.               R_FIXEDLEN
  50.                      The   records  are  fixed-length,  not  byte
  51.                      delimited.   The  structure  element  _r_e_c_l_e_n
  52.                      specifies  the length of the record, and the
  53.                      structure element _b_v_a_l is used  as  the  pad
  54.                      character.
  55.  
  56.               R_NOKEY
  57.                      In  the  interface  specified by _d_b_o_p_e_n, the
  58.                      sequential record retrieval  fills  in  both
  59.                      the  caller's  key  and data structures.  If
  60.                      the R_NOKEY flag is  specified,  the  _c_u_r_s_o_r
  61.  
  62.  
  63.  
  64.                         February 21, 1994                       1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. RECNO(3)                                                 RECNO(3)
  71.  
  72.  
  73.                      routines are not required to fill in the key
  74.                      structure.   This  permits  applications  to
  75.                      retrieve records at the end of files without
  76.                      reading all of the intervening records.
  77.  
  78.               R_SNAPSHOT
  79.                      This flag requires that a  snapshot  of  the
  80.                      file be taken when _d_b_o_p_e_n is called, instead
  81.                      of permitting any unmodified records  to  be
  82.                      read from the original file.
  83.  
  84.        cachesize
  85.               A  suggested  maximum size, in bytes, of the memory
  86.               cache.  This value is oonnllyy advisory, and the access
  87.               method  will allocate more memory rather than fail.
  88.               If _c_a_c_h_e_s_i_z_e is  0 (no size is specified) a default
  89.               cache is used.
  90.  
  91.        psize  The recno access method stores the in-memory copies
  92.               of its records in a btree.  This value is the  size
  93.               (in  bytes)  of  the  pages  used for nodes in that
  94.               tree.  If _p_s_i_z_e is 0 (no page size is specified)  a
  95.               page  size  is  chosen based on the underlying file
  96.               system I/O  block  size.   See  _b_t_r_e_e(3)  for  more
  97.               information.
  98.  
  99.        lorder The  byte order for integers in the stored database
  100.               metadata.  The number should represent the order as
  101.               an  integer; for example, big endian order would be
  102.               the number 4,321.  If _l_o_r_d_e_r  is  0  (no  order  is
  103.               specified) the current host order is used.
  104.  
  105.        reclen The length of a fixed-length record.
  106.  
  107.        bval   The delimiting byte to be used to mark the end of a
  108.               record for variable-length  records,  and  the  pad
  109.               character for fixed-length records.  If no value is
  110.               specified, newlines (``\n'') are used to  mark  the
  111.               end  of  variable-length  records  and fixed-length
  112.               records are padded with spaces.
  113.  
  114.        bfname The recno access method stores the in-memory copies
  115.               of  its records in a btree.  If bfname is non-NULL,
  116.               it specifies the name of  the  btree  file,  as  if
  117.               specified  as the file name for a dbopen of a btree
  118.               file.
  119.  
  120.        The data part of the  key/data  pair  used  by  the  recno
  121.        access  method  is  the same as other access methods.  The
  122.        key is different.  The _d_a_t_a field of the key should  be  a
  123.        pointer  to  a memory location of type _r_e_c_n_o___t, as defined
  124.        in the <db.h> include file.  This  type  is  normally  the
  125.        largest  unsigned integral type available to the implemen-
  126.        tation.  The _s_i_z_e field of the key should be the  size  of
  127.  
  128.  
  129.  
  130.                         February 21, 1994                       2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. RECNO(3)                                                 RECNO(3)
  137.  
  138.  
  139.        that type.
  140.  
  141.        In the interface specified by _d_b_o_p_e_n, using the _p_u_t inter-
  142.        face to create a new record will  cause  the  creation  of
  143.        multiple,  empty records if the record number is more than
  144.        one greater than  the  largest  record  currently  in  the
  145.        database.
  146.  
  147. SSEEEE AALLSSOO
  148.        _b_t_r_e_e(3), _d_b_o_p_e_n(3), _h_a_s_h(3), _m_p_o_o_l(3)
  149.  
  150.        _D_o_c_u_m_e_n_t  _P_r_o_c_e_s_s_i_n_g  _i_n  _a  _R_e_l_a_t_i_o_n_a_l  _D_a_t_a_b_a_s_e  _S_y_s_t_e_m,
  151.        Michael  Stonebraker,  Heidi  Stettner,   Joseph   Kalash,
  152.        Antonin  Guttman,  Nadene  Lynn,  Memorandum  No.  UCB/ERL
  153.        M82/32, May 1982.
  154.  
  155. BBUUGGSS
  156.        Only big and little endian byte order is supported.
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.                         February 21, 1994                       3
  197.  
  198.  
  199.